home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / SoundSprocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  15.1 KB  |  462 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        SoundSprocket.h
  3.  
  4.      Contains:    Games Sprockets: SoundSprocket interfaces
  5.  
  6.      Version:    Technology:    NetSprocket 1.0
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1996-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __SOUNDSPROCKET__
  19. #define __SOUNDSPROCKET__
  20.  
  21. #ifndef __TYPES__
  22. #include <Types.h>
  23. #endif
  24. #ifndef __EVENTS__
  25. #include <Events.h>
  26. #endif
  27. #ifndef __QD3D__
  28. #include <QD3D.h>
  29. #endif
  30. #ifndef __QD3DCAMERA__
  31. #include <QD3DCamera.h>
  32. #endif
  33.  
  34.  
  35.  
  36. #if PRAGMA_ONCE
  37. #pragma once
  38. #endif
  39.  
  40. #ifdef __cplusplus
  41. extern "C" {
  42. #endif
  43.  
  44. #if PRAGMA_IMPORT
  45. #pragma import on
  46. #endif
  47.  
  48. #if PRAGMA_STRUCT_ALIGN
  49.     #pragma options align=power
  50. #elif PRAGMA_STRUCT_PACKPUSH
  51.     #pragma pack(push, 2)
  52. #elif PRAGMA_STRUCT_PACK
  53.     #pragma pack(2)
  54. #endif
  55.  
  56. /*******************************************************************************
  57.  *    This stuff will be moved to Errors.h in a subsequent release
  58.  ******************************************************************************/
  59.  
  60. enum {
  61.     kSSpInternalErr                = -30340,
  62.     kSSpVersionErr                = -30341,
  63.     kSSpCantInstallErr            = -30342,
  64.     kSSpParallelUpVectorErr        = -30343,
  65.     kSSpScaleToZeroErr            = -30344
  66. };
  67.  
  68.  
  69. /*******************************************************************************
  70.  *    SndSetInfo/SndGetInfo Messages
  71.  ******************************************************************************/
  72. /*    The siSSpCPULoadLimit = '3dll' selector for SndGetInfo fills in a value of    */
  73. /*    type UInt32.                                                                */
  74.  
  75.  
  76. enum {
  77.     kSSpSpeakerKind_Stereo        = 0,
  78.     kSSpSpeakerKind_Mono        = 1,
  79.     kSSpSpeakerKind_Headphones    = 2
  80. };
  81.  
  82.  
  83. /*    This is the data type is used with the SndGet/SetInfo selector                */
  84. /*    siSSpSpeakerSetup = '3dst'                                                    */
  85. struct SSpSpeakerSetupData {
  86.     UInt32                             speakerKind;                /* Speaker configuration                */
  87.     float                             speakerAngle;                /* Angle formed by user and speakers    */
  88.  
  89.     UInt32                             reserved0;                    /* Reserved for future use -- set to 0    */
  90.     UInt32                             reserved1;                    /* Reserved for future use -- set to 0    */
  91. };
  92. typedef struct SSpSpeakerSetupData SSpSpeakerSetupData;
  93.  
  94.  
  95. enum {
  96.     kSSpMedium_Air                = 0,
  97.     kSSpMedium_Water            = 1
  98. };
  99.  
  100.  
  101.  
  102. enum {
  103.     kSSpSourceMode_Unfiltered    = 0,                            /* No filtering applied                    */
  104.     kSSpSourceMode_Localized    = 1,                            /* Localized by source position            */
  105.     kSSpSourceMode_Ambient        = 2,                            /* Coming from all around                */
  106.     kSSpSourceMode_Binaural        = 3                                /* Already binaurally localized            */
  107. };
  108.  
  109.  
  110. struct SSpLocationData {
  111.     float                             elevation;                    /* Angle of the meridian -- pos is up    */
  112.     float                             azimuth;                    /* Angle of the parallel -- pos is left    */
  113.     float                             distance;                    /* Distance between source and listener    */
  114.     float                             projectionAngle;            /* Cos(angle) between cone and listener    */
  115.     float                             sourceVelocity;                /* Speed of source toward the listener    */
  116.     float                             listenerVelocity;            /*Speed of listener toward the source    */
  117. };
  118. typedef struct SSpLocationData SSpLocationData;
  119.  
  120. struct SSpVirtualSourceData {
  121.     float                             attenuation;                /* Attenuation factor                    */
  122.     SSpLocationData                 location;                    /* Location of virtual source            */
  123. };
  124. typedef struct SSpVirtualSourceData SSpVirtualSourceData;
  125.  
  126. /*    This is the data type is used with the SndGet/SetInfo selector                */
  127. /*    siSSpLocalization = '3dif'                                                    */
  128. struct SSpLocalizationData {
  129.     UInt32                             cpuLoad;                    /* CPU load vs. quality -- 0 is best    */
  130.  
  131.     UInt32                             medium;                        /* Medium for sound propagation            */
  132.     float                             humidity;                    /* Humidity when medium is air            */
  133.     float                             roomSize;                    /* Reverb model -- distance bet. walls    */
  134.     float                             roomReflectivity;            /*Reverb model -- bounce attenuation    */
  135.     float                             reverbAttenuation;            /*Reverb model -- mix level            */
  136.  
  137.     UInt32                             sourceMode;                    /* Type of filtering to apply            */
  138.     float                             referenceDistance;            /*Nominal distance for recording        */
  139.     float                             coneAngleCos;                /* Cos(angle/2) of attenuation cone        */
  140.     float                             coneAttenuation;            /* Attenuation outside the cone            */
  141.     SSpLocationData                 currentLocation;            /* Location of the sound                 */
  142.  
  143.     UInt32                             reserved0;                    /* Reserved for future use -- set to 0    */
  144.     UInt32                             reserved1;                    /* Reserved for future use -- set to 0    */
  145.     UInt32                             reserved2;                    /* Reserved for future use -- set to 0    */
  146.     UInt32                             reserved3;                    /* Reserved for future use -- set to 0    */
  147.  
  148.     UInt32                             virtualSourceCount;            /*Number of reflections                */
  149.     SSpVirtualSourceData             virtualSource[4];            /*The reflections                        */
  150. };
  151. typedef struct SSpLocalizationData SSpLocalizationData;
  152.  
  153. #if TARGET_CPU_PPC
  154. typedef CALLBACK_API_C( Boolean , SSpEventProcPtr )(EventRecord *inEvent);
  155. /*******************************************************************************
  156.  *    Global functions
  157.  ******************************************************************************/
  158. EXTERN_API_C( OSStatus )
  159. SSpConfigureSpeakerSetup        (SSpEventProcPtr         inEventProcPtr);
  160.  
  161. EXTERN_API_C( OSStatus )
  162. SSpGetCPULoadLimit                (UInt32 *                outCPULoadLimit);
  163.  
  164.  
  165. /*******************************************************************************
  166.  *    Routines for Maniulating Listeners
  167.  ******************************************************************************/
  168. typedef struct OpaqueSSpListenerReference*  SSpListenerReference;
  169. EXTERN_API_C( OSStatus )
  170. SSpListener_New                    (SSpListenerReference *    outListenerReference);
  171.  
  172. EXTERN_API_C( OSStatus )
  173. SSpListener_Dispose                (SSpListenerReference     inListenerReference);
  174.  
  175. EXTERN_API_C( OSStatus )
  176. SSpListener_SetTransform        (SSpListenerReference     inListenerReference,
  177.                                  const TQ3Matrix4x4 *    inTransform);
  178.  
  179. EXTERN_API_C( OSStatus )
  180. SSpListener_GetTransform        (SSpListenerReference     inListenerReference,
  181.                                  TQ3Matrix4x4 *            outTransform);
  182.  
  183. EXTERN_API_C( OSStatus )
  184. SSpListener_SetPosition            (SSpListenerReference     inListenerReference,
  185.                                  const TQ3Point3D *        inPosition);
  186.  
  187. EXTERN_API_C( OSStatus )
  188. SSpListener_GetPosition            (SSpListenerReference     inListenerReference,
  189.                                  TQ3Point3D *            outPosition);
  190.  
  191. EXTERN_API_C( OSStatus )
  192. SSpListener_SetOrientation        (SSpListenerReference     inListenerReference,
  193.                                  const TQ3Vector3D *    inOrientation);
  194.  
  195. EXTERN_API_C( OSStatus )
  196. SSpListener_GetOrientation        (SSpListenerReference     inListenerReference,
  197.                                  TQ3Vector3D *            outOrientation);
  198.  
  199. EXTERN_API_C( OSStatus )
  200. SSpListener_SetUpVector            (SSpListenerReference     inListenerReference,
  201.                                  const TQ3Vector3D *    inUpVector);
  202.  
  203. EXTERN_API_C( OSStatus )
  204. SSpListener_GetUpVector            (SSpListenerReference     inListenerReference,
  205.                                  TQ3Vector3D *            outUpVector);
  206.  
  207. EXTERN_API_C( OSStatus )
  208. SSpListener_SetCameraPlacement    (SSpListenerReference     inListenerReference,
  209.                                  const TQ3CameraPlacement * inCameraPlacement);
  210.  
  211. EXTERN_API_C( OSStatus )
  212. SSpListener_GetCameraPlacement    (SSpListenerReference     inListenerReference,
  213.                                  TQ3CameraPlacement *    outCameraPlacement);
  214.  
  215. EXTERN_API_C( OSStatus )
  216. SSpListener_SetVelocity            (SSpListenerReference     inListenerReference,
  217.                                  const TQ3Vector3D *    inVelocity);
  218.  
  219. EXTERN_API_C( OSStatus )
  220. SSpListener_GetVelocity            (SSpListenerReference     inListenerReference,
  221.                                  TQ3Vector3D *            outVelocity);
  222.  
  223. EXTERN_API_C( OSStatus )
  224. SSpListener_GetActualVelocity    (SSpListenerReference     inListenerReference,
  225.                                  TQ3Vector3D *            outVelocity);
  226.  
  227. EXTERN_API_C( OSStatus )
  228. SSpListener_SetMedium            (SSpListenerReference     inListenerReference,
  229.                                  UInt32                 inMedium,
  230.                                  float                     inHumidity);
  231.  
  232. EXTERN_API_C( OSStatus )
  233. SSpListener_GetMedium            (SSpListenerReference     inListenerReference,
  234.                                  UInt32 *                outMedium,
  235.                                  float *                outHumidity);
  236.  
  237. EXTERN_API_C( OSStatus )
  238. SSpListener_SetReverb            (SSpListenerReference     inListenerReference,
  239.                                  float                     inRoomSize,
  240.                                  float                     inRoomReflectivity,
  241.                                  float                     inReverbAttenuation);
  242.  
  243. EXTERN_API_C( OSStatus )
  244. SSpListener_GetReverb            (SSpListenerReference     inListenerReference,
  245.                                  float *                outRoomSize,
  246.                                  float *                outRoomReflectivity,
  247.                                  float *                outReverbAttenuation);
  248.  
  249. EXTERN_API_C( OSStatus )
  250. SSpListener_SetMetersPerUnit    (SSpListenerReference     inListenerReference,
  251.                                  float                     inMetersPerUnit);
  252.  
  253. EXTERN_API_C( OSStatus )
  254. SSpListener_GetMetersPerUnit    (SSpListenerReference     inListenerReference,
  255.                                  float *                outMetersPerUnit);
  256.  
  257.  
  258. /*******************************************************************************
  259.  *    Routines for Manipulating Sources
  260.  ******************************************************************************/
  261. typedef struct OpaqueSSpSourceReference*  SSpSourceReference;
  262. EXTERN_API_C( OSStatus )
  263. SSpSource_New                    (SSpSourceReference *    outSourceReference);
  264.  
  265. EXTERN_API_C( OSStatus )
  266. SSpSource_Dispose                (SSpSourceReference     inSourceReference);
  267.  
  268. EXTERN_API_C( OSStatus )
  269. SSpSource_CalcLocalization        (SSpSourceReference     inSourceReference,
  270.                                  SSpListenerReference     inListenerReference,
  271.                                  SSpLocalizationData *    out3DInfo);
  272.  
  273. EXTERN_API_C( OSStatus )
  274. SSpSource_SetTransform            (SSpSourceReference     inSourceReference,
  275.                                  const TQ3Matrix4x4 *    inTransform);
  276.  
  277. EXTERN_API_C( OSStatus )
  278. SSpSource_GetTransform            (SSpSourceReference     inSourceReference,
  279.                                  TQ3Matrix4x4 *            outTransform);
  280.  
  281. EXTERN_API_C( OSStatus )
  282. SSpSource_SetPosition            (SSpSourceReference     inSourceReference,
  283.                                  const TQ3Point3D *        inPosition);
  284.  
  285. EXTERN_API_C( OSStatus )
  286. SSpSource_GetPosition            (SSpSourceReference     inSourceReference,
  287.                                  TQ3Point3D *            outPosition);
  288.  
  289. EXTERN_API_C( OSStatus )
  290. SSpSource_SetOrientation        (SSpSourceReference     inSourceReference,
  291.                                  const TQ3Vector3D *    inOrientation);
  292.  
  293. EXTERN_API_C( OSStatus )
  294. SSpSource_GetOrientation        (SSpSourceReference     inSourceReference,
  295.                                  TQ3Vector3D *            outOrientation);
  296.  
  297. EXTERN_API_C( OSStatus )
  298. SSpSource_SetUpVector            (SSpSourceReference     inSourceReference,
  299.                                  const TQ3Vector3D *    inUpVector);
  300.  
  301. EXTERN_API_C( OSStatus )
  302. SSpSource_GetUpVector            (SSpSourceReference     inSourceReference,
  303.                                  TQ3Vector3D *            outUpVector);
  304.  
  305. EXTERN_API_C( OSStatus )
  306. SSpSource_SetCameraPlacement    (SSpSourceReference     inSourceReference,
  307.                                  const TQ3CameraPlacement * inCameraPlacement);
  308.  
  309. EXTERN_API_C( OSStatus )
  310. SSpSource_GetCameraPlacement    (SSpSourceReference     inSourceReference,
  311.                                  TQ3CameraPlacement *    outCameraPlacement);
  312.  
  313. EXTERN_API_C( OSStatus )
  314. SSpSource_SetVelocity            (SSpSourceReference     inSourceReference,
  315.                                  const TQ3Vector3D *    inVelocity);
  316.  
  317. EXTERN_API_C( OSStatus )
  318. SSpSource_GetVelocity            (SSpSourceReference     inSourceReference,
  319.                                  TQ3Vector3D *            outVelocity);
  320.  
  321. EXTERN_API_C( OSStatus )
  322. SSpSource_GetActualVelocity        (SSpSourceReference     inSourceReference,
  323.                                  TQ3Vector3D *            outVelocity);
  324.  
  325. EXTERN_API_C( OSStatus )
  326. SSpSource_SetCPULoad            (SSpSourceReference     inSourceReference,
  327.                                  UInt32                 inCPULoad);
  328.  
  329. EXTERN_API_C( OSStatus )
  330. SSpSource_GetCPULoad            (SSpSourceReference     inSourceReference,
  331.                                  UInt32 *                outCPULoad);
  332.  
  333. EXTERN_API_C( OSStatus )
  334. SSpSource_SetMode                (SSpSourceReference     inSourceReference,
  335.                                  UInt32                 inMode);
  336.  
  337. EXTERN_API_C( OSStatus )
  338. SSpSource_GetMode                (SSpSourceReference     inSourceReference,
  339.                                  UInt32 *                outMode);
  340.  
  341. EXTERN_API_C( OSStatus )
  342. SSpSource_SetReferenceDistance    (SSpSourceReference     inSourceReference,
  343.                                  float                     inReferenceDistance);
  344.  
  345. EXTERN_API_C( OSStatus )
  346. SSpSource_GetReferenceDistance    (SSpSourceReference     inSourceReference,
  347.                                  float *                outReferenceDistance);
  348.  
  349. EXTERN_API_C( OSStatus )
  350. SSpSource_SetSize                (SSpSourceReference     inSourceReference,
  351.                                  float                     inLength,
  352.                                  float                     inWidth,
  353.                                  float                     inHeight);
  354.  
  355. EXTERN_API_C( OSStatus )
  356. SSpSource_GetSize                (SSpSourceReference     inSourceReference,
  357.                                  float *                outLength,
  358.                                  float *                outWidth,
  359.                                  float *                outHeight);
  360.  
  361. EXTERN_API_C( OSStatus )
  362. SSpSource_SetAngularAttenuation    (SSpSourceReference     inSourceReference,
  363.                                  float                     inConeAngle,
  364.                                  float                     inConeAttenuation);
  365.  
  366. EXTERN_API_C( OSStatus )
  367. SSpSource_GetAngularAttenuation    (SSpSourceReference     inSourceReference,
  368.                                  float *                outConeAngle,
  369.                                  float *                outConeAttenuation);
  370.  
  371. #endif  /* TARGET_CPU_PPC */
  372.  
  373.  
  374. /*******************************************************************************
  375.  *    LATE-BREAKING NEWS
  376.  *
  377.  *    After the documentation was completed, it was decided that the SSpSetup
  378.  *    were not specific enough.  We renamed them to SSpSpeakerSetup.  These
  379.  *    #defines allow code to be written per the documentation.  But please use
  380.  *    the new, longer names, as the #defines will be removed in a later release.
  381.  ******************************************************************************/
  382. #define SSpConfigureSetup        SSpConfigureSpeakerSetup
  383.  
  384. #define siSSpSetup                siSSpSpeakerSetup
  385. #define SSpSetupData            SSpSpeakerSetupData
  386.  
  387.  
  388. /*******************************************************************************
  389.  *    MORE LATE-BREAKING NEWS
  390.  *
  391.  *    The SndGetInfo selector siSSpFilterVersion and datatype SSpFilterVersionData
  392.  *    have been removed in favor of an alternate way of accessing filter version
  393.  *    information.  The following function may be used for this purpose.
  394.  *******************************************************************************
  395. // **************************** GetSSpFilterVersion ****************************
  396. // Finds the manufacturer and version number of the SoundSprocket filter that
  397. // may be installed.  inManufacturer should be the manufacturer code specified
  398. // at the installation time, which may be zero to allow any manufacturer.
  399. // If no error is encountered, outManufacturer is set to the actual manufacturer
  400. // code and outMajorVersion and outMinorVersion are set to the component
  401. // specification level and manufacturer's implementation revision, respectively.
  402. OSStatus GetSSpFilterVersion(
  403.     OSType                    inManufacturer,
  404.     OSType*                    outManufacturer,
  405.     UInt32*                    outMajorVersion,
  406.     UInt32*                    outMinorVersion)
  407. {
  408.     OSStatus                err;
  409.     ComponentDescription    description;
  410.     Component                componentRef;
  411.     UInt32                    vers;
  412.     
  413.     // Set up the component description
  414.     description.componentType            = kSoundEffectsType;
  415.     description.componentSubType        = kSSpLocalizationSubType;
  416.     description.componentManufacturer    = inManufacturer;
  417.     description.componentFlags            = 0;        
  418.     description.componentFlagsMask        = 0;    
  419.     
  420.     // Find a component matching the description
  421.     componentRef = FindNextComponent(nil, &description);
  422.     if (componentRef == nil)  return couldntGetRequiredComponent;
  423.     
  424.     // Get the component description (for the manufacturer code)
  425.     err = GetComponentInfo(componentRef, &description, nil, nil, nil);
  426.     if (err != noErr)  return err;
  427.     
  428.     // Get the version composite
  429.     vers = (UInt32) GetComponentVersion((ComponentInstance) componentRef);
  430.     
  431.     // Return the results
  432.     *outManufacturer = description.componentManufacturer;
  433.     *outMajorVersion = HiWord(vers);
  434.     *outMinorVersion = LoWord(vers);
  435.     
  436.     return noErr;
  437. }
  438. *******************************************************************************/
  439.  
  440.  
  441.  
  442. #if PRAGMA_STRUCT_ALIGN
  443.     #pragma options align=reset
  444. #elif PRAGMA_STRUCT_PACKPUSH
  445.     #pragma pack(pop)
  446. #elif PRAGMA_STRUCT_PACK
  447.     #pragma pack()
  448. #endif
  449.  
  450. #ifdef PRAGMA_IMPORT_OFF
  451. #pragma import off
  452. #elif PRAGMA_IMPORT
  453. #pragma import reset
  454. #endif
  455.  
  456. #ifdef __cplusplus
  457. }
  458. #endif
  459.  
  460. #endif /* __SOUNDSPROCKET__ */
  461.  
  462.